Skip to content

feat(results): average, median, range and a promoter score sub type for scale questions - #3635

Closed
global-prog wants to merge 12 commits into
nextcloud:feat/linearscale-ratingfrom
global-prog:contrib/response-statistics
Closed

global-prog wants to merge 12 commits into
nextcloud:feat/linearscale-ratingfrom
global-prog:contrib/response-statistics

Conversation

@global-prog

@global-prog global-prog commented Sep 9, 2026 •

Copy link
Copy Markdown

Stack

Part 2 of 2 of the linear scale stack. Merge in this order:

  1. feat(linearscale): rating sub type with stars, hearts or thumbs #3978 feat(linearscale): rating sub type with stars, hearts or thumbs
  2. feat(results): average, median, range and a promoter score sub type for scale questions #3635 (this PR) promoter score sub type and scale figures

This PR targets feat/linearscale-rating. After #3978 is merged, change its base to main before that branch is deleted. CI runs Playwright only for PRs into main, so the full suite was run locally on the top of the stack: 83 of 83 passed.

Screenshots (stacked PR)

👀 🌞 🌚
Editor forms-linear-scale-editor-light forms-linear-scale-editor-dark
Results forms-linear-scale-results-light forms-linear-scale-results-dark
Public link forms-linear-scale-public-link-light forms-linear-scale-public-link-dark
Embedded form forms-linear-scale-embedded-form-light forms-linear-scale-embedded-form-dark

Summary

Scale questions currently show a bar per value, which makes it hard to compare two questions, or two runs of the same form, at a glance.

This adds a small set of figures above the existing bars for linearscale questions:

  • number of answers, average, median, minimum, maximum, formatted for the user's locale
  • for a promoter score question, a new sub type of the linear scale with a fixed 0–10 range, the promoter score (promoters − detractors) with its promoter and detractor shares (the usual 9–10 / 7–8 / 0–6 split)

The median sits next to the average deliberately — at the response counts most forms see, one extreme answer moves an average a long way, and showing both makes that visible.

The promoter score is labelled by its calculation rather than with the name of the method, which is a registered trademark of Bain & Company, NICE Systems and Fred Reichheld.

Scope

  • the figures are shown above the existing per-value bars; questions of other types render as before
  • a rating (feat(linearscale): rating sub type with stars, hearts or thumbs #3978) gets none of these figures: it already shows its bars per level and "Average rating x of N, from n ratings"
  • the promoter score is a sub type of the linear scale, as discussed in feat(results): average, median, range and a promoter score sub type for scale questions #3635 (comment). The shared sub type code (the questionType extra setting, the sub type check on creation, the FormsQuestionSubtype API type and the "Linear scale" sub menu with Numbers) comes from feat(linearscale): rating sub type with stars, hearts or thumbs #3978; this PR adds Promoter score as the third entry, after Rating
  • creating a promoter score question stores the range 0 to 10; the server rejects any other range for it, both on creation and on update. The editor shows no range pickers for it; the label fields stay and default to "Not at all likely" and "Extremely likely"
  • the results show the score only for the promoter score sub type. Existing linear scale questions have no sub type, so they stay plain numeric scales and never show a score
  • POST /api/v3/forms/{formId}/questions accepts subtype: promoter for linearscale; openapi.json, docs/API_v3.md and docs/DataStructure.md are updated. No schema change, no migration

How to verify

  1. In a form, choose "Add a question" → "Linear scale" → "Promoter score": the question shows 0 ("Not at all likely") to 10 ("Extremely likely"), and its actions menu has no "Lowest value" / "Highest value" pickers.
  2. Answer it a few times (logged in, public link or embedded) and open the results: the summary shows answers, average, median, minimum, maximum and "Promoter score (promoters − detractors)" with the shares.
  3. Add "Linear scale" → "Numbers" and set it to 0 to 10: its results show the figures but no promoter score.
  4. Add "Linear scale" → "Rating" and answer it: its results show "Average rating …" and no figures.

Testing

  • every commit passes npm run lint and npm run build; npm run stylelint, Prettier and vue-tsc show no new findings on the top of the stack
  • PHP unit tests for the promoter range validation (FormsServiceTest) and for creating a promoter score question (ApiControllerTest)
  • Playwright: playwright/e2e/results-scale-figures.spec.ts covers the figures and the score, no score on a plain 0–10 scale, no figures on a rating, and both the "Promoter score" and "Numbers" menu entries
  • checked on NC 35: the promoter score and rating results in the logged-in app, axe clean on the results page

History

Based on the work of the original contributor of this PR. The commits that show the scale figures and the promoter score in the results carry their authorship and sign-off. Their original contribution, before the rework: 86a6e87d (average, median, range and promoter score for scale questions).

🤖 AI (if applicable)

  • The content of this PR was partly or fully generated using AI

@global-prog
global-prog force-pushed the contrib/response-statistics branch from 4f0ebc9 to 6eedc91 Compare September 9, 2026 00:58
@Chartman123

Copy link
Copy Markdown
Collaborator

@global-prog Thanks for your contribution. As said in the other PR: please create an issue/feature request before starting implentation to discuss it. Also please add screenshots to the description with before/after. This should also be added to the new rating quetions in #3637.

Also please add the AI declaration to your description if you used AI for this.

@Chartman123 Chartman123 added this to the 5.5 milestone Sep 11, 2026
@global-prog

Copy link
Copy Markdown
Author

Thanks, noted on opening an issue first. I'll add before/after screenshots to the description. The AI declaration is added there as well.

@github-actions

Copy link
Copy Markdown
Contributor

Hello there,
Thank you so much for taking the time and effort to create a pull request to our Nextcloud project.

We hope that the review process is going smooth and is helpful for you. We want to ensure your pull request is reviewed to your satisfaction. If you have a moment, our community management team would very much appreciate your feedback on your experience with this PR review process.

Your feedback is valuable to us as we continuously strive to improve our community developer experience. Please take a moment to complete our short survey by clicking on the following link: https://cloud.nextcloud.com/apps/forms/s/i9Ago4EQRZ7TWxjfmeEpPkf6

Thank you for contributing to Nextcloud and we hope to hear from you soon!

(If you believe you should not receive this message, you can add yourself to the blocklist.)

@Chartman123 Chartman123 added the stale On hold label Oct 30, 2026
@Chartman123 Chartman123 modified the milestones: 5.5, 5.6 Nov 20, 2026
@AndyScherzinger
AndyScherzinger force-pushed the contrib/response-statistics branch from 99fc214 to f698725 Compare November 21, 2026 00:01
@AndyScherzinger AndyScherzinger changed the title feat(results): average, median, range and Net Promoter Score for scale questions feat(results): average, median, range and promoter score for scale questions Nov 21, 2026
@AndyScherzinger
AndyScherzinger force-pushed the contrib/response-statistics branch 2 times, most recently from b1f0b88 to 01b75fc Compare November 21, 2026 00:22
@AndyScherzinger
AndyScherzinger force-pushed the contrib/response-statistics branch from 2e6777e to 8720401 Compare November 21, 2026 22:18
@AndyScherzinger
AndyScherzinger force-pushed the contrib/response-statistics branch from 8720401 to de2ce1c Compare November 22, 2026 10:02
@AndyScherzinger
AndyScherzinger force-pushed the contrib/response-statistics branch from de2ce1c to ad3506d Compare November 22, 2026 10:30
@AndyScherzinger
AndyScherzinger force-pushed the contrib/response-statistics branch from ad3506d to b456ccb Compare November 22, 2026 11:38
AndyScherzinger and others added 12 commits November 22, 2026 15:53
A rating ("how would you rate this") is answered with one whole number
from 1 to N, which a linear scale already stores, validates, counts in
the results and exports. It therefore becomes a sub type of the linear
scale rather than a question type of its own: fixed when the question
is created and stored in extraSettings.questionType, the way grid
questions store their cell type.

The add-question menu lists "Numbers" and "Rating" under "Linear
scale". The editor of a rating offers only the highest rating (2 to
10, default 5), since a rating always starts at 1. Answers, results
and exports go through the existing linear scale paths; the results
summary names a rating "Linear scale (Rating)".

The server accepts no other sub type of a linear scale and keeps a
rating starting at 1. Existing linear scale questions have no sub type
and stay as they are.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
Drawn as a row of radio buttons with labels, a rating is not the
compact control people expect for it. A rating now draws stars, hearts
or thumbs up (extraSettings.ratingIcon) instead of the radio buttons
and labels, still built from real radio inputs. Each is named by its
value like the options of a plain scale, as screen readers announce
its position ("3 of 5") themselves, lies over its icon so that screen
readers highlight the icon, and has a hit area of
--default-clickable-area. The icons wrap, and the hover effect is
dropped under reduced motion. The editor offers the icon next to the
highest rating.

The server accepts ratingIcon only on a rating and only with one of
the known icons, and accepts no labels on a rating, which shows none.

Closes nextcloud#2608

Based on the original implementation by global-prog, reworked by Andy Scherzinger.

Signed-off-by: global-prog <raqeeb@uosamarra.edu.iq>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
Create the question through "Linear scale" > "Rating" and check what
unit tests cannot: the accessible names of the rating and its options,
restoring an answer from a draft and when editing a response, the error
of a required rating and that picking a rating clears it, Enter moving
on to the submit button instead of submitting the form, focus and the
insert menu of a new rating, and the highest rating and the icon chosen
in the editor.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
A required linear scale left empty shows "You must answer this
question" and marks its radio buttons invalid. A rating cleared both as
soon as a value was picked, while a plain scale kept them until the
next submit attempt, so screen readers went on announcing the picked
value as invalid.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
In the editor the radio buttons of a linear scale referenced the
question title as their group name and the label of the lowest value as
the description of the first one, but both are only rendered on the
submit page, so the references pointed nowhere. On the submit page the
description of the first radio button pointed nowhere as well when the
label of the lowest value is empty. Both are now set only where the
element exists, as for a rating.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
A rating is read as "4.3 of 5 stars", so the results summary of a
rating question shows its average rating and how many ratings it is
based on, above the counts per value.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The first entry of the sub menu of "Grid" and "Linear scale" in the
add-question menu leads back to all question types, but it was named
only after the question type, like the entry that opened the sub menu,
and it is the entry that receives focus. A screen reader user could
not tell that it goes back. It is now named, for example, "Linear
scale, back to all question types".

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The editor offered the icons of a rating as a caption and three radio
entries in the question's actions menu, which made the menu long. A
dropdown labelled "Icon" now takes their place, built like the
"Highest rating" input above it, and shows the chosen icon in front of
it. "Highest rating" shows the pencil of the other range inputs again,
so the menu shows the chosen icon only once. The list shows the names
only, as NcActionInput passes no option slot on to its select.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
A 0-10 scale is not always a "how likely are you to recommend"
question, and switching a scale that already has answers to 0-10
would score those answers on the wrong scale. The promoter score is
therefore a sub type of the linear scale, fixed when the question is
created and stored in extraSettings.questionType next to "Numbers"
and "Rating" in the add-question menu.

Creating a promoter score question stores the range 0 to 10, the
server rejects any other range for it, and the editor shows no range
pickers for it. Its lowest and highest values are labelled "Not at all
likely" and "Extremely likely" unless the author changes them, as
"Strongly disagree" and "Strongly agree" do not fit a likelihood.
Existing scales have no sub type and keep working as before.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
…m for scale questions

Scale questions only show a bar per value, which makes it hard to
compare two questions or two runs of the same form at a glance. The
summary now lists the number of answers, the average, the median, the
minimum and the maximum above the bars. The median sits next to the
average because, at the response counts most forms see, a single
extreme answer moves an average a long way.

The figures are formatted for the user's locale and are derived from
the per-value counts the bars already compute, so the answers are not
walked a second time. A rating keeps its own "Average rating" line
and gets no figures. No API or schema change; other question types
are unaffected.

Based on the original implementation by global-prog, reworked by Andy Scherzinger.

Signed-off-by: global-prog <raqeeb@uosamarra.edu.iq>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
A promoter score question splits respondents into promoters (9-10),
passives (7-8) and detractors (0-6). The summary of such a question
now adds the promoter score, the share of promoters minus the share
of detractors, together with both shares. The score is rounded from
the exact difference rather than computed from the rounded shares,
which can be one point off (4 promoters and 2 detractors out of 7
give 29, not 28). Plain scales, including plain 0-10 scales, show no
score.

Based on the original implementation by global-prog, reworked by Andy Scherzinger.

Signed-off-by: global-prog <raqeeb@uosamarra.edu.iq>
Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
The figures and the promoter score are computed in the frontend only,
which has no unit tests, so end-to-end tests are their only coverage.
They check the figures above the bars of a scale question, the promoter
score of the promoter sub type, its absence on a plain 0-10 scale, the
absence of the figures on a rating, and the questions the add-question
menu creates for the "Promoter score" and "Numbers" entries, including
the default labels of a promoter score question.

Assisted-by: ClaudeCode:claude-opus-5-5
Signed-off-by: Andy Scherzinger <info@andy-scherzinger.de>
@AndyScherzinger

Copy link
Copy Markdown
Member

Thank you for this contribution, and @Chartman123 for the review so far.

This work continues in #3984. The branch moved from the fork to nextcloud/forms, so CI runs on it without approval for every push. The commits are the same, and the commits that show the scale figures and the promoter score in the results keep their original authorship and sign-off. Changes made during review are separate commits on top of them, so the original contribution stays visible as it was.

#3984 builds on #3978 (rating sub type) and adds the figures as cards and a dashboard-style promoter score. Please continue the review there. Closing this one in favour of #3984.

Assisted by ClaudeCode:claude-opus-5-5

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants